<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="umsroot.css">
<TITLE>
Garbage collection
</TITLE>
</HEAD>
<BODY >
<A HREF="umsroot122.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot121.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc271">19.2</A>&nbsp;&nbsp;Garbage collection</H2>
<A NAME="@default1093"></A>
<A NAME="gc"></A>
The four stacks grow an shrink as needed<SUP><A NAME="text31" HREF="umsroot121.html#note31">1</A></SUP>.
In addition, ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> provides an incremental garbage collector
for the global and the trail stack.
It is also equipped with a dictionary garbage
collector that frees memory that is occupied by obsolete atoms and functors.
Both collectors are switched on by default and are automatically invoked
from time to time.
Nevertheless, there are some predicates to control their action.
The following predicates affect both collectors:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>set_flag(gc, on).</B><DD CLASS="dd-description">
<A NAME="@default1094"></A>
	Enable the garbage collector (the default).
<DT CLASS="dt-description"><B>set_flag(gc, verbose).</B><DD CLASS="dd-description">
	The same as 'on', but print a message on every collection
	(the message goes to toplevel_output):
<PRE CLASS="verbatim">
GC ... global: 96208 - 88504 (92.0 %), trail: 500 - 476 (95.2 %), time: 0.017
</PRE>
	It displays the area to be searched for garbage, the amount
	and percentage of garbage, and the time for the collection.
	The message of the dictionary collector is as follows:
<PRE CLASS="verbatim">
DICTIONARY GC ... 2814 - 653, (23.2 %), time: 0.033
</PRE>
	It displays the number of dictionary entries before the collection,
	the number of collected entries, the percentage of reduction and
	the collection time.
<DT CLASS="dt-description"><B>set_flag(gc, off).</B><DD CLASS="dd-description">
	Disable the garbage collector (and risk an overflow), eg. for
	time-critical execution sequences.
</DL>
Predicates related to the stack collector are:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>set_flag(gc_policy, adaptive).</B><DD CLASS="dd-description">
	This option affects the triggering heuristics of the garbage
	collector, together with the gc_interval setting.
	The adaptive policy (the default) minimises garbage collection time.
<DT CLASS="dt-description"><B>set_flag(gc_policy, fixed).</B><DD CLASS="dd-description">
	This option affects the triggering heuristics of the garbage
	collector, together with the gc_interval setting.
	The fixed policy minimises space consumption. 
<DT CLASS="dt-description"><B>set_flag(gc_interval, Nbytes).</B><DD CLASS="dd-description">
	Specify how often the collector is invoked. Roughly, Nbytes
	is the number of bytes that your program can use up before
	a garbage collection is triggered.
	There may be programs that create lots of (useful) lists and
	structures while leaving few garbage. This will cause the garbage
	collector to run frequently while reclaiming little space.
	If you suspect this, you should call statistics/0 and check
	the garbage ratio. If it is very low (say below 50%) it may
	make sense to increase the <TT>gc_interval</TT>, thus reducing
	the number of garbage collections. This is normally only
	necessary when the gc_policy is set to fixed. With gc_policy
	set to adaptive, the collection intervals will be adjusted
	automatically.
<DT CLASS="dt-description"><B>garbage_collect.</B><DD CLASS="dd-description">
<A NAME="@default1095"></A>
	Request an immediate collection (only if enabled). The use of this
	predicate should be restricted to situations where the automatic
	triggering performs badly. It should then be inserted in a place
	where you know for sure that you have just created a lot of garbage,
	eg. before the tail-recursive call in something like
<PRE CLASS="verbatim">
        cycle(OldState) :-
                transform(OldState, NewState),  /* long computation     */
                !,
                garbage_collect,                /* OldState is obsolete */
                cycle(NewState).
</PRE><DT CLASS="dt-description"><B>statistics(gc_number, N).</B><DD CLASS="dd-description">
<A NAME="@default1096"></A>
	The number of stack garbage collections performed during this ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> session.
<DT CLASS="dt-description"><B>statistics(gc_collected, Bytes).</B><DD CLASS="dd-description">
	The amount of global stack space reclaimed by all the
	garbage collections in bytes.
<DT CLASS="dt-description"><B>statistics(gc_area, Bytes).</B><DD CLASS="dd-description">
	The average global stack area that was scanned by each garbage
	collection. This number should be close to the selected
	<TT>gc_interval</TT>, if it is much larger, <TT>gc_interval</TT>
	should be increased.
<DT CLASS="dt-description"><B>statistics(gc_ratio, Percentage).</B><DD CLASS="dd-description">
	The average percentage of garbage found and reclaimed by each
	garbage collection.
	If this ratio is low, <TT>gc_interval</TT> should be increased.
<DT CLASS="dt-description"><B>statistics(gc_time, Seconds).</B><DD CLASS="dd-description">
	The total cputime spent during all garbage collections.
</DL>
Predicates related to the dictionary collector are:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>set_flag(gc_interval_dict, N).</B><DD CLASS="dd-description">
	Specify that the dictionary collector should be invoked after
	N new dictionary entries have been made.
<DT CLASS="dt-description"><B>statistics(dict_gc_number, N).</B><DD CLASS="dd-description">
 The number of dictionary garbage collections performed during this ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> session.
<DT CLASS="dt-description"><B>statistics(dict_gc_time, Seconds).</B><DD CLASS="dd-description">
 The total cputime spent by all dictionary garbage collections.
</DL>
<HR>
<A HREF="umsroot122.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot121.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
</BODY>
</HTML>
